safe-stable-stringify

What is safe-stable-stringify?

The safe-stable-stringify npm package is used to convert JavaScript objects into a JSON string representation in a deterministic order. It ensures that objects with the same content will result in the same JSON string, regardless of the order in which their properties were defined. It also handles circular references and other edge cases that can cause JSON.stringify to throw errors.

What are safe-stable-stringify's main functionalities?

Deterministic JSON.stringify

This feature ensures that the JSON string output is consistent for the same object content, which is important for tasks like caching and comparison.

{"result": "safeStableStringify({ key1: 'value1', key2: 'value2' })"}

Handling circular references

safe-stable-stringify can handle objects that have circular references without throwing an error, unlike the native JSON.stringify.

{"result": "safeStableStringify(circularReference)"}

Custom replacer function

This feature allows for a custom replacer function to be used, similar to the replacer parameter in JSON.stringify, to customize the stringification process.

{"result": "safeStableStringify(obj, (key, value) => value instanceof RegExp ? String(value) : value)"}

Other packages similar to safe-stable-stringify

json-stable-stringify

This package offers similar functionality to safe-stable-stringify by providing a deterministic version of JSON.stringify. It ensures consistent ordering of object keys but does not handle circular references.

fast-json-stable-stringify

This is a faster implementation of json-stable-stringify without support for handling circular references. It is designed for performance-critical applications.

flatted

Flatted is a package that can serialize and deserialize objects with circular references to and from a flat JSON structure. It differs from safe-stable-stringify by focusing on the flat structure and the ability to reconstruct the original object, including circular references.

README

safe-stable-stringify

Safe, deterministic and fast serialization alternative to JSON.stringify.

Gracefully handles circular structures instead of throwing.

Usage

The same as JSON.stringify.

stringify(value[, replacer[, space]])

const stringify = require('safe-stable-stringify')
const o = { b: 1, a: 0 }
o.o = o

console.log(stringify(o))
// '{"a":0,"b":1,"o":"[Circular]"}'
console.log(JSON.stringify(o))
// TypeError: Converting circular structure to JSON

function replacer(key, value) {
  console.log('Key:', JSON.stringify(key))
  // Remove the circular structure
  if (key === 'o') {
    return
  }
  return value
}
const serialized = stringify(o, replacer, 2)
// Key: ""
// Key: "a"
// Key: "b"
// Key: "o"
console.log(serialized)
// {
//   "a": 0,
//   "b": 1
// }

Differences to JSON.stringify

1. replace circular structures with the string [Circular]
2. sorted keys instead of using the insertion order

Those are the only differences to the real JSON.stringify. This is a side effect free variant and toJSON, replacer and the spacer work the same as with the native JSON.stringify.

Performance / Benchmarks

Currently this is by far the fastest known stable stringify implementation. This is especially important for big objects.

(Lenovo T450s with a i7-5600U CPU using Node.js 8.9.4)

simple:   simple object x 1,733,045 ops/sec ±1.82% (86 runs sampled)
simple:   circular      x 717,021 ops/sec ±0.78% (91 runs sampled)
simple:   deep          x 17,674 ops/sec ±0.77% (94 runs sampled)
simple:   deep circular x 17,396 ops/sec ±0.70% (93 runs sampled)

replacer:   simple object x 1,126,942 ops/sec ±2.22% (91 runs sampled)
replacer:   circular      x 541,243 ops/sec ±0.87% (94 runs sampled)
replacer:   deep          x 17,229 ops/sec ±0.90% (94 runs sampled)
replacer:   deep circular x 16,948 ops/sec ±0.86% (97 runs sampled)

array:   simple object x 1,470,751 ops/sec ±0.84% (95 runs sampled)
array:   circular      x 1,360,269 ops/sec ±2.94% (91 runs sampled)
array:   deep          x 1,289,785 ops/sec ±2.82% (87 runs sampled)
array:   deep circular x 1,400,577 ops/sec ±1.00% (92 runs sampled)

Comparing safe-stable-stringify with known alternatives:

fast-json-stable-stringify x 9,336 ops/sec ±0.64% (90 runs sampled)
json-stable-stringify x 7,512 ops/sec ±0.63% (91 runs sampled)
fast-stable-stringify x 11,674 ops/sec ±0.58% (92 runs sampled)
faster-stable-stringify x 8,893 ops/sec ±0.51% (92 runs sampled)
json-stringify-deterministic x 6,240 ops/sec ±0.68% (94 runs sampled)
fast-safe-stringify x 15,939 ops/sec ±0.42% (96 runs sampled)
this x 24,048 ops/sec ±0.44% (91 runs sampled)

The fastest is this

The fast-safe-stringify comparison uses the modules stable implementation.

Acknowledgements

Sponsored by nearForm

License

MIT

Changelog

v1.1.1

• Fixed an indentation issue in combination with empty arrays and objects
• Updated dev dependencies